[Agents] Improve MPP payment guides - #32185

Fix the following review findings in PR #32185 (https://github.com/cloudflare/cloudflare-docs/pull/32185).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.

---

## Code Review

### Warnings (4)

#### CR-0ba19327ef74 · Uses deprecated McpAgent API
- **File:** `src/content/docs/agents/tools/payments/mpp/accept-payments.mdx` line 137
- **Issue:** The MCP tool example extends McpAgent and links to /agents/model-context-protocol/apis/agent-api/. Repository docs for that page and related how-to pages state that McpAgent is deprecated, feature-frozen, and that createMcpHandler is the recommended approach for new stateless MCP servers.
- **Fix:** Rewrite the MCP tool example to use createMcpHandler from agents/mcp with the SDK v2 @modelcontextprotocol/server factory pattern, since the payment flow appears stateless. If mppx/server currently requires McpAgent, add a deprecation note and a migration pointer to createMcpHandler.

#### CR-95854bd6667c · Unrestricted automatic MCP payments
- **File:** `src/content/docs/agents/tools/payments/mpp/pay-from-agents-sdk.mdx` line 132
- **Issue:** The MCP example wraps the raw MCP client with payment methods and calls `premium_search` without an `onPaymentRequired` handler or a server/tool allowlist. Unlike the HTTP example, which restricts automatic payments to `https://api.example.com` via `acceptPaymentPolicy`, this snippet could auto-pay any compatible challenge from the connected MCP server.
- **Fix:** If `McpClient.wrap` supports an allowlist or approval callback, configure it here to mirror the HTTP example's origin restriction. Otherwise, add a note warning readers that automatic MCP payments require the same scoping/approval controls as HTTP payments.

#### CR-56f18f4874e7 · Inaccurate protocol header description
- **File:** `src/content/docs/agents/tools/payments/index.mdx` line 39
- **Issue:** The sentence states MPP "adds the `WWW-Authenticate: Payment` and `Authorization: Payment` headers to HTTP `402` responses.`Authorization: Payment` is sent by the client on the retried request, not by the server in the 402 response.
- **Fix:** Clarify the direction of each header: the server returns `WWW-Authenticate: Payment` on the 402 response, and the client retries with `Authorization: Payment`.

#### CR-1dc0ce419532 · Mismatched LinkCard description
- **File:** `src/content/docs/agents/tools/payments/index.mdx` line 53
- **Issue:** The card title is `HTTP content (x402)`, but its description now reads `Gate APIs, web pages, and files with the mpp-proxy Worker` — the `mpp-proxy` Worker is specific to MPP, not x402.
- **Fix:** Restore the x402-specific description, e.g. `Gate APIs, web pages, and files with a Worker proxy`, or otherwise match the description to the x402 guide.

### Suggestions (1)

#### CR-9c9b5045b6ca · Duplicate card description
- **File:** `src/content/docs/agents/tools/payments/index.mdx` line 58
- **Issue:** The `HTTP content (MPP)` card currently uses the same text as the x402 card (`Gate APIs, web pages, and files with the mpp-proxy Worker`), so the descriptions do not distinguish the two protocol guides.
- **Fix:** Give each card a distinct description, ensuring the x402 card does not mention `mpp-proxy` and the MPP card clearly describes its own approach.

---

## Style Guide Review

### Suggestions (1)

#### SG-c104d40c785b · Bullet list with fewer than three items
- **File:** `src/content/docs/agents/tools/payments/index.mdx` line 34
- **Issue:** The x402 integration list has only two bullets: "Server-side" and "Client-side".
- **Fix:** Consider converting the two-item bullet list into prose.